Comprehensive Usage Manual & Examples

This manual provides an operational guide for Pepvoid Builder, with architecture profiles, output formats, compression options, and usage examples.

1. Supported Architecture Targets Matrix

Pepvoid Builder accepts 22 build targets: 17 architecture profile names and five additional board targets. A configured target does not certify that every corresponding physical device has been tested.

Target Name

Architecture Family

C Standard Library

Target Hardware

Default Engine

x86_64

x86 64-bit

glibc

Standard Intel/AMD 64-bit PCs & Laptops

VoidEngine

x86_64-musl

x86 64-bit

musl

Lightweight 64-bit PCs & Servers

VoidEngine

i686

x86 32-bit

glibc

Legacy 32-bit Intel/AMD PCs

VoidEngine

aarch64

ARM64 64-bit

glibc

Generic ARM64 Servers & Workstations

VoidEngine

aarch64-musl

ARM64 64-bit

musl

Lightweight ARM64 Containers & SBCs

VoidEngine

armv7l

ARMv7 32-bit

glibc

Generic 32-bit ARMv7 Hard-Float SBCs

VoidEngine

armv7l-musl

ARMv7 32-bit

musl

Lightweight 32-bit ARMv7 Devices

VoidEngine

armv6l

ARMv6 32-bit

glibc

Generic ARMv6 targets

VoidEngine

armv6l-musl

ARMv6 32-bit

musl

ARMv6 musl targets

VoidEngine

riscv64

RISC-V 64-bit

glibc

Generic RISC-V targets

VoidEngine

riscv64-musl

RISC-V 64-bit

musl

RISC-V musl targets

VoidEngine

rpi-aarch64

ARM64 64-bit

glibc

Raspberry Pi 3, 4, 400, 5, Zero 2 W

PlatformEngine

rpi-armv7l

ARMv7 32-bit

glibc

Raspberry Pi 2, 3 (32-bit mode)

PlatformEngine

rpi-armv6l

ARMv6 32-bit

glibc

Raspberry Pi 1, Zero (32-bit ARMv6)

PlatformEngine

pinebookpro

ARM64 64-bit

glibc

Pine64 Pinebook Pro (Rockchip RK3399)

PlatformEngine

asahi

ARM64 64-bit

glibc

Apple Silicon Macs (M1, M1 Pro/Max, M2)

PlatformEngine

x13s

ARM64 64-bit

glibc

Lenovo ThinkPad X13s

PlatformEngine

rockpro64

ARM64 64-bit

glibc

Pine64 RockPro64

PlatformEngine

pine64

ARM64 64-bit

glibc

Pine A64

PlatformEngine

odroid-c4

ARM64 64-bit

glibc

Hardkernel ODROID-C4

PlatformEngine

odroid-n2

ARM64 64-bit

glibc

Hardkernel ODROID-N2/N2+

PlatformEngine

visionfive2

RISC-V 64-bit

glibc

StarFive VisionFive 2

PlatformEngine

2. Output Formats Explained

Pepvoid Builder supports multiple production output formats specified via --format:

A. Bootable ISO Image (--format iso)

  • Extension: .iso

  • Use Case: Bootable Live USB flash drives, DVDs, live virtual machine testing (QEMU, KVM, VirtualBox, VMware).

  • Structure: Hybrid ISO 9660 filesystem containing a SquashFS container image (LiveOS/squashfs.img), El Torito BIOS MBR boot code (SYSLINUX), and UEFI FAT boot image (boot/grub/efiboot.img).

B. Virtual Machine Disk Images (--format qcow2, --format vdi, --format vmdk, --format vhdx)

  • QEMU / KVM (--format qcow2): Compressed, sparse copy-on-write virtual disk image ready for qemu-system-*, virt-manager, Proxmox VE, or OpenStack.

  • VirtualBox (--format vdi): Native VirtualBox disk image ready to attach directly to a VM.

  • VMware (--format vmdk): Native VMware Workstation / Player / ESXi virtual machine disk.

  • Hyper-V (--format vhd, --format vhdx): Microsoft Virtual Hard Disk and Virtual Hard Disk v2 formats.

  • Structure: Partitioned virtual disk (GPT: EFI System Partition + ext4 rootfs, pre-installed GRUB2 bootloader, /etc/fstab with UUIDs, kernel, and customized user stack).

C. Raw Platform & Flashable Disk Image (--format img, --format raw)

  • Extension: .img / .raw

  • Use Case: Single-Board Computers (Raspberry Pi, Pinebook Pro, Apple Silicon Asahi, ThinkPad X13s) and physical SSD/USB drive cloning. Designed to be flashed directly using dd, Raspberry Pi Imager, or BalenaEtcher.

  • Structure: Partitioned disk image (Partition 1: VFAT /boot partition; Partition 2: EXT4 root / partition).

D. RootFS Container Tarball (--format tarball, --format container)

  • Extension: .tar.xz or .tar.zst (selected by --compression)

  • Use Case: Docker container base images, Podman containers, LXC/Proxmox templates, systemd-nspawn containers, chroot bootstrap environments.

  • Structure: Compressed tar archive containing the exact customized root directory structure (/bin, /etc, /usr, /var).

3. Stage Seed Tarball System (Gentoo-Style Rapid ISO Builds)

Pepvoid Builder incorporates a Stage Seed Tarball mechanism inspired by Gentoo Linux’s Stage3 seed architecture:

  1. --use-tarball [SOURCE]:

    • Unpacks a pre-built base rootfs tarball (void-base-<arch>.tar.xz) directly into the target chroot.

    • Automatically runs xbps-install -Syu inside the chroot to bring base packages up to the latest Void Linux repository release.

    • Reuses the stage’s installed base packages and layers requested desktop and package profiles. Build time depends on package changes, network, and host performance.

    • Supported Sources:

      • --use-tarball y / --use-tarball auto: Automatically looks for cached stage seeds in output/stage_seeds/ or cache/tarballs/.

      • Local file: /path/to/stage.tar.xz or file:///...

      • Remote URL: https://... (downloads and caches the tarball automatically; plain HTTP is rejected).

    • In real mode, SHA-256 is checked before extraction. Supply --tarball-sha256 <64-hex-digest> or provide a valid <tarball>.sha256 sidecar beside the local/cached tarball. A remote URL needs the explicit digest because its sidecar is not fetched automatically. This detects content mismatch; it does not establish who published the tarball.

  2. --create-tarball:

    • Saves the bootstrapped base rootfs as a reusable stage seed in the stage cache and writes SHA-256, SHA-512, MD5, and manifest sidecars. Real builds verify SHA-256 before reusing a seed.

4. Compression Algorithms Compared

Select the compression algorithm via --compression:

Algorithm

Compression Ratio

Decompression Speed

CPU Usage

Best For

xz (default)

Very High (Smallest file size)

Moderate

High

Distribution ISOs, internet downloads

zstd

Depends on data and level

Often faster to decompress than xz

Depends on data and level

When decompression speed matters

gzip

Moderate

Fast

Low

Compatibility with legacy systems

4. Complete Usage Examples

Example 1: Standard Non-Root Simulation (Mock Build)

Simulate an x86_64 ISO build with XFCE desktop environment without root privileges. This produces placeholder output and does not test bootability:

python3 cli.py x86_64 -d xfce --mode mock

Use --mode real for a bootable artifact. The --output option chooses its path; the example below creates output/pepvoid-xfce.iso.

sudo python3 cli.py x86_64 --preset desktop-xfce --mode real \
  --output output/pepvoid-xfce.iso

Real builds perform package downloads and system image creation. A mock build does not test whether the resulting image boots.

.. _artifact-checksums-manifests-and-signatures:

Artifact Checksums, Manifests & Signatures

The .asc file is a detached GPG signature for the artifact. From the directory containing the downloaded files, check the hash and signature with:

sha256sum -c <artifact>.sha256
gpg --import <artifact>.gpg-key.asc
gpg --verify <artifact>.asc <artifact>

A successful hash check confirms the ISO matches the accompanying checksum. A Good signature confirms it matches the accompanying public key. The builder creates a fresh key for each build and deletes its private key afterward. Since the public key is distributed beside the artifact, this signature alone does not authenticate the publisher. Authenticate a release only when its key fingerprint has been independently published through a trusted channel.

Example 2: RAM-Backed Build with Benchmark Timings

Place the build work tree in RAM-backed storage and report per-stage timings. This requires enough available memory and is not guaranteed to be faster:

sudo python3 cli.py x86_64 --preset desktop-xfce --fast --tmpfs --benchmark --mode real

Example 3: Specialized Flavour Build (Rescue & Maintenance Edition)

Build the focused XFCE recovery and maintenance ISO, with its own offline tool center:

sudo python3 cli.py x86_64 --preset rescue-sysadmin --mode real --output pepvoid-rescue-x86_64.iso

See Rescue & Maintenance for the included tools and validation checklist.

Example 4: Education Edition for Older School Computers

Build the XFCE classroom core, or add subject groups for older students:

sudo python3 cli.py x86_64 --preset education --mode real --output pepvoid-education-x86_64.iso
sudo python3 cli.py x86_64 --preset education \\
    -p education-lower-secondary -p education-upper-secondary \\
    --mode real --output pepvoid-education-secondary-x86_64.iso

The installer creates a standard user and requests a separate root password. Keep that administrator credential with school staff. See the Education Edition plan for account protections and package groups.

Example 5: Full Localization & System Configuration

Build an ISO customized with Portuguese localization, custom hostname, and root credentials:

sudo python3 cli.py x86_64 -P desktop-xfce \
    --hostname void-portugal \
    --locale pt_PT.UTF-8 \
    --timezone Europe/Lisbon \
    --keymap pt-latin1 \
    --root-password "SecretPass123" \
    --mode real

Example 5: Developer Workstation with SSH Key Ingestion

Build a developer environment with Rust, Go, Python, Podman, and inject your host SSH public key:

sudo python3 cli.py x86_64 --preset developer \
    --ssh-key ~/.ssh/id_ed25519.pub \
    --mode real

Example 6: Gaming Edition with Steam & Multilib

Build the x86_64 glibc Gaming prototype with Plasma Wayland, Gaming Center, Steam, Lutris, Wine, Gamescope, MangoHud and explicit 32-bit graphics/audio dependencies:

sudo python3 cli.py x86_64 --preset gaming --mode real --output pepvoid-gaming-x86_64.iso

See Gaming Edition for included software, per-game settings and the remaining hardware qualification checks.

Example 7: Raspberry Pi 4 64-Bit Disk Image

Generate a bootable SD Card image for Raspberry Pi 4/5:

# Setup host cross-emulation once
sudo ./setup_host_build_env.sh

# Build Raspberry Pi 64-bit disk image
sudo python3 cli.py rpi-aarch64 --mode real

Example 8: Lifecycle Hooks Execution

Execute customized shell scripts during build phases:

sudo python3 cli.py x86_64 -P minimal \
    --hook post-install:configs/hooks/post-install.example.sh \
    --mode real

Example 9: Container RootFS Export

Export a customized Void Linux rootfs tarball for LXC, Docker, or Podman:

sudo python3 cli.py x86_64 -P minimal --format tarball --mode real

Example 10: Calamares Graphical Installer Live ISO

Compile the Calamares graphical installer and inject it into an XFCE live ISO:

sudo python3 cli.py x86_64 -d xfce --with-calamares --mode real